Ereignisse

Admin Power Pack tauscht Ereignisse („FpEvents") mit anderen Fluxpunkt-Modulen aus: Es empfängt Steuerereignisse, die dieselben Wartungs- und Systemaktionen auslösen wie die XML-RPC-Befehle und die HTTP-API, und sendet je Wartungsaktion ein Abschlussereignis mit dem Ergebnis — nur die Systemaktionen Neustart und Update senden keines. Typische Konsumenten sind EventBridge (Weiterleitung als Webhook, E-Mail, Syslog oder Datenbankeintrag) und eigene STARFACE-Module, die Ereignisse direkt abonnieren oder senden. Seit Modulversion 26.8.19 sendet Admin Power Pack zusätzlich das Audit-Ereignis McpToolCalledEvent für jeden Aufruf des MCP-Servers. Über ExecuteModuleInstallation installieren und aktualisieren sich Fluxpunkt-Module gegenseitig — so hebt der Module Manager das Admin Power Pack auf eine neue Version. Über AttentionEvent melden Module Probleme an den Administrator und an den betreuenden Partner im StarfleetController.

Verwendung durch Dritte

Diese Schnittstelle ist für die Nutzung durch Drittsysteme freigegeben. Änderungen und Erweiterungen werden je Version in den Release Notes dokumentiert.

Grundlagen

• Typ: FpEvents — der modulübergreifende Ereignismechanismus der Fluxpunkt-Module auf dem anlageninternen Ereignisbus. Es handelt sich um keine Netzwerkschnittstelle: Ereignisse sind nur innerhalb der Anlage erreichbar; nach außen gelangen sie über EventBridge.
• Identifikator: der Ereignisname, z. B. ExecuteDeleteLogs oder LogsDeletedEvent. Die Namen sind anlagenweit gültig und unabhängig vom Namen der Modulkonfiguration.
• Nutzlast: ein JSON-Objekt. Felder ohne Wert (null) entfallen in der Nutzlast; unbekannte Felder werden beim Empfang ignoriert.
• Zugriff: EventBridge abonniert Ereignisse per Konfiguration und kann Steuerereignisse als Aktion senden. Eigene Module verwenden die Modulfunktionen FpEvent abonnieren / FpEvent senden — Download und Anleitung im Artikel Schnittstellen & APIs. Zusätzlich sendet Admin Power Pack die Wartungs-Steuerereignisse selbst zeitgesteuert über die Geplanten Aktionen im Tab STARFACE Verwaltung; die Systemaktions-Ereignisse planen stattdessen über ihr Feld executeAt.
• Lizenz: Die Ausführung empfangener Steuerereignisse ist lizenzgebunden — ohne gültige Modullizenz werden sie verworfen (Eintrag im Modul-Log).
• Verfügbar seit: Wartungsereignisse Modulversion 26.6.12, Benutzervorlagen-Ereignisse Modulversion 26.5.8; die Systemaktions-Ereignisse ExecuteStarfaceRestart und ExecuteStarfaceUpdate sowie das MCP-Audit-Ereignis McpToolCalledEvent seit Modulversion 26.8.19; die Modulinstallation und AttentionEvent ab dem nächsten Release

Gemeinsame Felder

Alle Wartungsereignisse — Steuer- wie Abschlussereignisse — tragen zwei gemeinsame Felder:

Feld	Typ	Beschreibung
trigger	String	Herkunft der Ausführung: EVENT (anderes Modul/Ereignis), TIMER (Geplante Aktion), MANUAL (Schaltfläche in der Moduloberfläche), API (XML-RPC- oder HTTP-API-Aufruf). In Steuerereignissen optional; fehlt der Wert oder ist er unbekannt, gilt EVENT. Das Abschlussereignis übernimmt den Wert des auslösenden Steuerereignisses.
timerName	String, optional	Name der Geplanten Aktion, die den Befehl ausgelöst hat; nur bei trigger = TIMER gesetzt, sonst nicht enthalten.

Empfangene Steuerereignisse

Jedes Steuerereignis löst genau eine Wartungsaktion aus. Die Felder und ihre Bedeutung entsprechen den Parametern des jeweiligen XML-RPC-Befehls — zuzüglich der gemeinsamen Felder.

Ereignis	Wirkung	Felder (zusätzlich zu trigger, timerName)
ExecuteAutoCleanup	Auto-Cleanup ausführen	–
ExecuteDeleteSystemMessages	Systemmeldungen löschen	–
ExecuteDeleteLogs	Logdateien löschen	scope: old | all (Standard old)
ExecuteDeleteTemporaryFiles	Temporäre Dateien löschen	–
ExecuteDeleteRecordings	Gesprächsaufzeichnungen löschen	–
ExecuteDeleteFaxes	Faxe löschen	–
ExecuteDeleteCallData	Ruflisteneinträge löschen	startTime, endTime (Zeitstempel in ms), incoming, outgoing, missed, answered (Boolean, Standard true), filter (String), confirmed (Boolean, muss true sein)
ExecuteDeleteFirmware	Firmware-Dateien löschen	vendor: all | snom | yealink | gigaset | other (Standard all)
ExecuteDeleteBackups	Sicherungen löschen	scope: all | allExceptLast (Standard allExceptLast)
ExecuteReRegisterTrunks	Leitungen neu anmelden	–
ExecuteHangupAllCalls	Alle Gespräche beenden	–
ExecuteProvisionDevices	Endgeräte provisionieren	type: check-sync | check-sync-reboot | reboot-snom | factory-reset-snom | factory-reset-yealink (Pflicht)

Beispiel-Nutzlasten — ein parameterloses Steuerereignis und zwei mit Parametern:

ExecuteAutoCleanup

{
  "trigger": "TIMER"
}

ExecuteDeleteLogs

{
  "scope": "old",
  "trigger": "TIMER"
}

ExecuteDeleteCallData

{
  "startTime": 0,
  "endTime": 1767225600000,
  "incoming": true,
  "outgoing": true,
  "missed": true,
  "answered": true,
  "filter": "+4972112345678",
  "confirmed": true,
  "trigger": "EVENT"
}

ExecuteDeleteCallData ohne confirmed = true und ExecuteProvisionDevices ohne type werden still verworfen.

ExecuteUserTemplate — Benutzervorlage anwenden

Zusätzlich zu den Wartungsbefehlen empfängt Admin Power Pack ein Steuerereignis, das eine Benutzervorlage aus dem Tab Benutzer & Gruppen auf STARFACE-Benutzer anwendet. Gruppen in accountIds werden transitiv zu ihren Mitgliedern aufgelöst.

Feld	Typ	Pflicht	Beschreibung
templateId	String	ja	ID der Benutzervorlage. Ereignisse mit unbekannter ID werden verworfen.
accountIds	Array von Integer	ja	Account-IDs der Zielbenutzer oder -gruppen; leere Listen werden verworfen.
includeAdmins	Boolean	nein	Auch Benutzer mit Administrationsrecht einbeziehen (Standard false).

ExecuteUserTemplate

{
  "templateId": "3f2b7c9e-5d41-4c8a-9b1f-2a6d8e4f7c10",
  "accountIds": [12, 17, 23],
  "includeAdmins": false
}

Systemaktionen

Verfügbar seit Modulversion 26.8.19

Die beiden Systemaktions-Ereignisse sind seit Modulversion 26.8.19 enthalten; ältere Modulversionen ignorieren sie.

Admin Power Pack empfängt zwei Steuerereignisse für die Systemaktionen der Karte Setup & Recovery: STARFACE-Neustart und STARFACE-Update — sofort oder einmalig zu einem geplanten Zeitpunkt (executeAt). Eine zukünftige Planung wird gespeichert, überdauert Modul-Neustarts und wird durch ein neues Ereignis ersetzt; die Moduloberfläche zeigt sie an und kann sie abbrechen. Verstreicht ein geplanter Zeitpunkt, während Modul oder Anlage nicht laufen, holt das Modul die Aktion kurz nach dem nächsten Modulstart nach (etwa 30 Sekunden Verzögerung).

Ereignis	Wirkung	Felder (zusätzlich zu trigger, timerName)
ExecuteStarfaceRestart	STARFACE neu starten — entspricht RestartStarface	mode: service (nur STARFACE-Dienste, Standard) | server (kompletter Server); executeAt: ISO-8601-Zeitpunkt (JJJJ-MM-TTThh:mm, Anlagenzeit) — leer/vergangen = sofort, zukünftig = einmalig geplant
ExecuteStarfaceUpdate	STARFACE-Update ausführen — entspricht UpdateStarface	version: verfügbare Zielversion; latest oder leer = neueste angebotene Version (inkl. Beta, falls in der Anlage aktiviert); executeAt: wie bei ExecuteStarfaceRestart

Beide Aktionen senden kein Abschlussereignis — Neustart bzw. Update beenden die STARFACE-Dienste, eine Bestätigung ist danach nicht mehr möglich. trigger und timerName dürfen mitgesendet werden, bleiben ohne Abschlussereignis aber ohne sichtbare Wirkung. ExecuteStarfaceRestart mit ungültigem mode und ExecuteStarfaceUpdate mit nicht verfügbarer Zielversion werden still verworfen (Log-Eintrag).

ExecuteStarfaceRestart

{
  "mode": "service",
  "executeAt": "2026-08-12T22:00",
  "trigger": "EVENT"
}

ExecuteStarfaceUpdate

{
  "version": "latest",
  "executeAt": "2026-08-12T22:00",
  "trigger": "EVENT"
}

Gesendete Abschlussereignisse

Nach jeder ausgeführten Wartungsaktion veröffentlicht Admin Power Pack genau ein Abschlussereignis. Es bestätigt die tatsächliche Ausführung — im Gegensatz zur XML-RPC-Antwort, die nur die Annahme meldet — und übernimmt trigger und timerName des Auslösers. Die Systemaktionen Neustart und Update senden kein Abschlussereignis.

Ereignis	Folgt auf	Felder (zusätzlich zu trigger, timerName)
AutoCleanupExecutedEvent	ExecuteAutoCleanup	–
SystemMessagesDeletedEvent	ExecuteDeleteSystemMessages	–
LogsDeletedEvent	ExecuteDeleteLogs	scope — der wirksame Umfang (old/all)
TemporaryFilesDeletedEvent	ExecuteDeleteTemporaryFiles	–
RecordingsDeletedEvent	ExecuteDeleteRecordings	–
FaxesDeletedEvent	ExecuteDeleteFaxes	–
CallDataDeletedEvent	ExecuteDeleteCallData	deletedSummary (Integer) — gelöschte Ruflisteneinträge; deletedData (Integer) — gelöschte Detailzeilen; message (String) — Ergebnistext
FirmwareDeletedEvent	ExecuteDeleteFirmware	vendor — der wirksame Hersteller
BackupsDeletedEvent	ExecuteDeleteBackups	scope — der wirksame Umfang (all/allExceptLast)
TrunksReRegisteredEvent	ExecuteReRegisterTrunks	–
AllCallsHungUpEvent	ExecuteHangupAllCalls	–
DevicesProvisionedEvent	ExecuteProvisionDevices	type — der gesendete Provisionierungstyp

message in CallDataDeletedEvent nimmt einen der folgenden Werte an: „Alle Ruflisteneinträge wurden gelöscht." (vollständige Löschung), „Ruflisteneinträge wurden gelöscht." (Zeit-/Kategorienfilter), „Gefilterte Ruflisteneinträge wurden gelöscht." (Rufnummern-/Namensfilter) oder „Fehler beim Löschen." (Abbruch, Zähler dann 0).

Beispiel-Nutzlasten:

AutoCleanupExecutedEvent — ausgelöst durch eine Geplante Aktion

{
  "trigger": "TIMER",
  "timerName": "Nächtliche Bereinigung"
}

LogsDeletedEvent — ausgelöst per XML-RPC

{
  "scope": "old",
  "trigger": "API"
}

CallDataDeletedEvent

{
  "deletedSummary": 1284,
  "deletedData": 5210,
  "message": "Ruflisteneinträge wurden gelöscht.",
  "trigger": "API"
}

DevicesProvisionedEvent

{
  "type": "check-sync-reboot",
  "trigger": "API"
}

Anwendungsbeispiel

Sie stoßen abends per XML-RPC eine Provisionierung mit check-sync-reboot an. EventBridge abonniert DevicesProvisionedEvent und meldet den Abschluss als Nachricht in Ihren Teams-Kanal — Ihr Deployment-Skript muss nicht pollen, und das Protokoll zeigt, ob der Rollout zeitgesteuert oder per API lief.

UserTemplateExecutedEvent — Benutzervorlage angewendet

Wird nach jeder Anwendung einer Benutzervorlage veröffentlicht — gleich, ob sie manuell in der Oberfläche, über einen Vorlagen-Timer oder per ExecuteUserTemplate ausgelöst wurde. Bei Timer-Ausführung erscheint das Ereignis je angewendeter Vorlage mehrfach (einmal je Zielbenutzer), jeweils mit der vollständigen Kontenliste.

Feld	Typ	Beschreibung
templateId	String	ID der angewendeten Benutzervorlage.
templateName	String	Name der Benutzervorlage.
accountIds	Array von Integer	Account-IDs der Zielbenutzer (Gruppen bereits aufgelöst).
includeAdmins	Boolean	Ob Administratoren einbezogen wurden.
trigger	String	MANUAL (Oberfläche), TIMER (Vorlagen-Timer) oder EVENT (ExecuteUserTemplate). Der Wert API kommt hier nicht vor.
timerName	String, optional	Name des Vorlagen-Timers; nur bei trigger = TIMER.

UserTemplateExecutedEvent

{
  "templateId": "3f2b7c9e-5d41-4c8a-9b1f-2a6d8e4f7c10",
  "templateName": "Standard-Benutzer",
  "accountIds": [12, 17, 23],
  "includeAdmins": false,
  "trigger": "TIMER",
  "timerName": "Nächtlicher Abgleich"
}

MCP-Audit-Ereignis (McpToolCalledEvent)

Der MCP-Server veröffentlicht für jede Anfrage, die seinen Endpunkt erreicht, ein McpToolCalledEvent — für erfolgreiche Werkzeugaufrufe ebenso wie für abgewiesene. Das Modul führt bewusst keine eigene Audit-Tabelle: Wer den MCP-Zugriff protokollieren will, abonniert dieses Ereignis (typisch: Weiterleitung an Syslog über EventBridge). Die Argumente des Werkzeugaufrufs sind nicht enthalten — sie können Klartext-Kundendaten tragen; was der Aufruf berührt hat, fasst target zusammen.

Feld	Typ	Beschreibung
timestamp	Integer	Zeitpunkt der Beantwortung (Millisekunden-Zeitstempel).
tokenLabel	String	Bezeichnung des authentifizierenden API-Tokens — nie der Token selbst. Entfällt, wenn die Anfrage vor der Token-Prüfung abgewiesen wurde.
remoteAddr	String	Quelladresse — bei vertrauenswürdigem Proxy die aufgelöste Client-Adresse.
tool	String	Werkzeugname, z. B. status_overview. Entfällt, wenn die Anfrage vor der Werkzeugauflösung abgewiesen wurde.
operation	String	Operation innerhalb des Werkzeugs, z. B. get. Entfällt, wenn nicht aufgelöst.
mode	String	Wirksamer Modus des Werkzeugs zum Aufrufzeitpunkt: READ oder READ_WRITE.
destructive	Boolean	Ob die Operation als destruktiv eingestuft ist.
confirmed	Boolean	Ob der Aufrufer confirm: true übergeben hat.
durationMs	Integer	Dauer des Aufrufs in Millisekunden.
resultChars	Integer	Größe des serialisierten Ergebnisses in Zeichen; 0 bei abgewiesenen Aufrufen.
outcome	String	Ausgang: OK, TOOL_ERROR (fachlicher Fehler), DENIED_IP, DENIED_TOKEN, DENIED_LICENSE, DENIED_TOOL_DISABLED (Server aus oder Werkzeug nicht freigegeben), DENIED_READ_ONLY, DENIED_UNCONFIRMED (destruktiv ohne confirm: true) oder FAILED (interner Fehler).
target	String, optional	Kurze, unkritische Zusammenfassung dessen, was der Aufruf berührt hat.
error	String, optional	Fehlertext bei fehlgeschlagenen Aufrufen.

McpToolCalledEvent — erfolgreicher Leseaufruf

{
  "timestamp": 1755640800000,
  "tokenLabel": "Claude Code (F. Wolf)",
  "remoteAddr": "192.168.10.42",
  "tool": "status_trunks",
  "operation": "lines",
  "mode": "READ",
  "destructive": false,
  "confirmed": false,
  "durationMs": 184,
  "resultChars": 2311,
  "outcome": "OK"
}

McpToolCalledEvent — abgewiesener Aufruf (Token ungültig)

{
  "timestamp": 1755640860000,
  "remoteAddr": "203.0.113.7",
  "destructive": false,
  "confirmed": false,
  "durationMs": 0,
  "resultChars": 0,
  "outcome": "DENIED_TOKEN"
}

Die DENIED_…-Einträge sind gerade die, die in ein Syslog gehören: Sie zeigen abgewiesene Zugriffsversuche mit Quelladresse und Grund.

Modulinstallation (ExecuteModuleInstallation)

Neu

Verfügbar ab dem nächsten Release von Admin Power Pack und Module Manager. Ältere Modulversionen ignorieren das Ereignis.

Ein Modul kann sich nicht selbst aktualisieren: Die Installation schaltet das Modul ab, das sie ausführt. Mit ExecuteModuleInstallation beauftragt deshalb ein Modul ein anderes, eine Installation durchzuführen. Auf jeder Anlage mit Admin Power Pack ist der Module Manager installiert — er übernimmt die Aktualisierung des Admin Power Pack, und das Admin Power Pack umgekehrt die des Module Manager.

Das Ereignis gehört nicht zu einem einzelnen Modul, sondern zur gemeinsamen Basis aller Fluxpunkt-Module. Jedes Fluxpunkt-Modul ab dem genannten Stand kann Auftraggeber und Ausführender sein. Welches Modul ausführt, bestimmt das Feld executorModuleId.

So läuft eine Installation ab:

1. Ein Auftraggeber — ein Modul, eine EventBridge-Aktion oder eine Geplante Aktion — sendet ExecuteModuleInstallation.
2. Das in executorModuleId genannte Modul prüft den Auftrag. Bei mehreren Konfigurationen dieses Moduls führt nur eine aus.
3. Ist der Auftrag gültig, sendet es sofort ModuleInstallationAcceptedEvent und startet die Installation fünf Sekunden später. So kann ein Auftraggeber, der sich selbst aktualisieren lässt, seine laufende Anfrage noch beantworten.
4. Die Installation lädt die Zielversion vom Update-Server, prüft die Prüfsumme, sichert die Einstellungen des Zielmoduls, installiert und spielt die Sicherung wieder ein. Die Konfigurationen des Zielmoduls sind währenddessen kurz abgeschaltet.
5. Zum Schluss sendet das ausführende Modul ModuleInstallationExecutedEvent mit dem Ergebnis. Ob die Installation gelungen ist, liest es dafür aus der Modulverwaltung der Anlage zurück.

ExecuteModuleInstallation — Installation beauftragen

Feld	Typ	Pflicht	Beschreibung
executorModuleId	String	ja	Modul-Kennung des Moduls, das die Installation ausführt, z. B. der Module Manager: c2ccd2c1-d74b-48c4-a462-2c1b2eb97eb7. Das Modul muss installiert und aktiv sein.
targetModuleId	String	ja	Modul-Kennung des zu installierenden oder zu aktualisierenden Moduls. Darf nicht gleich executorModuleId sein.
targetVersion	Integer	ja	Zielversion. Sie muss vom Update-Server für dieses Modul angeboten werden.
allowDowngrade	Boolean	nein	Erlaubt eine Version, die kleiner ist als die installierte (Standard false).
requestId	String	nein	Kennung des Auftrags. Beide Antwortereignisse tragen sie. Fehlt sie, vergibt das ausführende Modul eine UUID.
requestedBy	String	nein	Freitext zur Herkunft, z. B. die Modul-Kennung des Auftraggebers. Erscheint im Modul-Log und in den Antworten; wird nicht geprüft.
trigger, timerName	String	nein	wie bei den gemeinsamen Feldern; Standard EVENT.

Ist das Zielmodul noch nicht installiert, wird es neu installiert. Die Modul-Kennungen und angebotenen Versionen liefert das MCP-Werkzeug read_modules (list, list_versions); die Modul-Kennung steht außerdem im Modul-Katalog unter /data/all.json.

ExecuteModuleInstallation — Admin Power Pack durch den Module Manager aktualisieren

{
  "executorModuleId": "c2ccd2c1-d74b-48c4-a462-2c1b2eb97eb7",
  "targetModuleId": "7ce0d8df-e9c8-42f6-a021-7a6e0bb44b88",
  "targetVersion": 20261003,
  "allowDowngrade": false,
  "requestId": "0b7c7a4e-3f55-4d1a-9f0e-6b2f8f1d2c11",
  "requestedBy": "Nächtliches Modul-Update"
}

ModuleInstallationAcceptedEvent

Der Auftrag ist gültig und startet zum Zeitpunkt startsAt.

Feld	Typ	Beschreibung
requestId	String	Kennung des Auftrags.
executorModuleId, executorModuleName, executorModuleVersion	String, String, Integer	Das ausführende Modul.
targetModuleId	String	Das Zielmodul.
requestedVersion	Integer	Die beauftragte Version.
previousVersion	Integer, optional	Bisher installierte Version; fehlt, wenn das Modul noch nicht installiert ist.
startsAt	Integer	Startzeitpunkt der Installation (Millisekunden-Zeitstempel).
requestedBy	String, optional	aus dem Auftrag übernommen.

ModuleInstallationExecutedEvent

Das Ergebnis — nach der Installation oder sofort, wenn der Auftrag abgelehnt wird.

Feld	Typ	Beschreibung
requestId	String	Kennung des Auftrags.
executorModuleId	String	Das ausführende Modul.
targetModuleId, targetModuleName	String	Das Zielmodul.
requestedVersion	Integer	Die beauftragte Version.
previousVersion	Integer, optional	Version vor dem Auftrag.
installedVersion	Integer, optional	Version danach, aus der Modulverwaltung gelesen.
success	Boolean	true, wenn die beauftragte Version installiert ist.
changed	Boolean	false, wenn die Version schon installiert war und nichts getan wurde.
error	String, optional	Fehlercode, siehe unten; fehlt bei Erfolg.
requestedBy, trigger, timerName	String	aus dem Auftrag übernommen.

error	Bedeutung
INVALID_REQUEST	targetModuleId oder targetVersion fehlt.
SELF_INSTALLATION	Ausführendes Modul und Zielmodul sind identisch.
VERSION_NOT_AVAILABLE	Der Update-Server bietet die Version für dieses Modul nicht an.
DOWNGRADE_NOT_ALLOWED	Die Version ist kleiner als die installierte, allowDowngrade fehlt.
INSTALL_FAILED	Die Installation lief, aber die Zielversion ist danach nicht installiert — etwa nach einem fehlgeschlagenen Download oder weil die Version nicht zu dieser STARFACE passt.

ModuleInstallationExecutedEvent — erfolgreich

{
  "requestId": "0b7c7a4e-3f55-4d1a-9f0e-6b2f8f1d2c11",
  "executorModuleId": "c2ccd2c1-d74b-48c4-a462-2c1b2eb97eb7",
  "targetModuleId": "7ce0d8df-e9c8-42f6-a021-7a6e0bb44b88",
  "targetModuleName": "Admin Power Pack",
  "requestedVersion": 20261003,
  "previousVersion": 20260925,
  "installedVersion": 20261003,
  "success": true,
  "changed": true,
  "requestedBy": "Nächtliches Modul-Update",
  "trigger": "EVENT"
}

Kein Absender-Nachweis

Der Ereignisbus prüft nicht, wer ein Ereignis sendet. Jede Stelle, die Ereignisse senden kann — eine EventBridge-Aktion, ein eingehender Webhook, eine Geplante Aktion oder ein eigenes Modul —, kann damit Module installieren. Die Installation ist auf Versionen aus dem signierten Update-Katalog beschränkt; einen Rückschritt auf eine ältere Version gibt es nur mit allowDowngrade. Sichern Sie eingehende Webhooks, die dieses Ereignis auslösen, mit einem X-Webhook-Secret ab.

Anders als die Wartungsereignisse ist die Modulinstallation nicht lizenzgebunden — der Module Manager ist kostenlos und führt sie ohne Lizenz aus.

Anwendungsbeispiel

Ein Systemhaus will Modul-Updates nicht mehr tagsüber einspielen. Ein Geplantes Event in EventBridge sendet nachts um 2 Uhr ExecuteModuleInstallation an den Module Manager, ein Handler leitet ModuleInstallationExecutedEvent als Nachricht an den Teams-Kanal der Technik weiter. Am Morgen steht dort, welche Version jetzt läuft — oder warum das Update nicht stattgefunden hat.

Anwendungsbeispiel

Ein KI-Agent soll das Admin Power Pack über den MCP-Server aktualisieren. exec_modules / install mit der eigenen Modul-Kennung reicht den Auftrag an den Module Manager weiter und antwortet mit „angenommen“. Eine Minute später prüft der Agent mit read_modules / get, ob die neue Version läuft.

Aufmerksamkeit melden (AttentionEvent)

Neu

Verfügbar ab dem nächsten Release von Admin Power Pack und der Fluxpunkt-Modulbasis.

Mit AttentionEvent macht ein Modul auf ein Problem aufmerksam, das ein Mensch ansehen sollte. Admin Power Pack empfängt jedes dieser Ereignisse, gleich von welchem Modul, und macht daraus zwei Dinge:

1. Einen STARFACE-Systemreport. Er erscheint in der Administration der STARFACE und in der Reportansicht von Admin Power Pack. Betreff: „Modul: Betreff“, Inhalt: die Beschreibung.
2. Eine Meldung im StarfleetController. Voraussetzung: Die Anlage ist angebunden und ein Partner ist freigegeben. Die Meldung erscheint dort in der Karte Aufmerksamkeit und lässt sich bestätigen – siehe StarfleetController – API – Aufmerksamkeit.

Senden darf jedes Modul, auch ein eigenes oder die EventBridge. Die Fluxpunkt-Module bringen das Ereignis ab der nächsten Version ihrer gemeinsamen Basis mit.

Feld	Typ	Pflicht	Beschreibung
module	String	ja	Anzeigename des meldenden Moduls, z. B. Call Recording. Fehlt er, steht „Unbekanntes Modul“ im Report.
moduleId	String	nein	Modulkennung (sfmId). Hält die Meldung auch über eine Umbenennung des Moduls zusammen.
timestamp	Integer	nein	Zeitpunkt der Erkennung (Millisekunden-Zeitstempel). Fehlt er, gilt der Empfangszeitpunkt.
subject	String	ja	Kurzer, gleichbleibender Name des Problems, höchstens 200 Zeichen. Ereignisse ohne Betreff werden verworfen.
description	String	nein	Ursache und nächste Schritte, höchstens 4000 Zeichen.
severity	String	nein	INFO, WARNING, ERROR oder CRITICAL. Standard WARNING.

AttentionEvent

{
  "module": "Call Recording",
  "moduleId": "de.fluxpunkt.callrecording",
  "timestamp": 1790920800000,
  "subject": "Aufzeichnungsziel nicht erreichbar",
  "description": "Die Freigabe \\\\nas01\\aufnahmen antwortet nicht. Aufnahmen werden lokal zwischengespeichert, bis das Ziel wieder erreichbar ist.",
  "severity": "ERROR"
}

Betreff ohne wechselnde Werte

Der StarfleetController fasst Meldungen mit gleichem Modul und gleichem Betreff zu einem Eintrag zusammen und zählt die Wiederholungen. Schreiben Sie Uhrzeiten, Zähler oder Messwerte deshalb in die Beschreibung, nicht in den Betreff. Sonst entsteht bei jeder Meldung ein neuer Eintrag.

Keine Kundendaten

Betreff und Beschreibung verlassen die Anlage in Richtung Partner. Namen, Rufnummern oder E-Mail-Adressen gehören nicht hinein.

Schwere im Systemreport

severity	Kategorie	Priorität
INFO	Modulreport	INFO
WARNING	Modulreport	WARNING
ERROR	Fehler	CRITICAL
CRITICAL	Fehler	FATAL

Drosselung. Der Systemreport entsteht für jedes Ereignis. An den Controller gehen je Modul höchstens 5 Meldungen auf einmal und danach eine alle zwei Minuten. Zurückgehaltene Meldungen zählt Admin Power Pack und meldet die Anzahl mit der nächsten weitergeleiteten Meldung. Ist die Verbindung zum Controller unterbrochen, hält Admin Power Pack bis zu 20 Meldungen zurück und sendet sie nach dem Wiederverbinden. Für den Systemreport braucht Admin Power Pack keine Modullizenz.

Anwendungsbeispiel

Ein Kunde betreibt eine Netzwerkspeicher-Überwachung, die bei vollem Speicher einen Webhook an die EventBridge schickt. Die EventBridge sendet daraufhin ein AttentionEvent mit Betreff „Speicher für Aufzeichnungen fast voll“ und Schwere WARNING. Der Administrator sieht den Systemreport, und der betreuende Partner hat die Meldung am nächsten Morgen in seiner Karte Aufmerksamkeit – bevor die ersten Aufnahmen verloren gehen.

Fehlerbehandlung

Der Ereignisweg arbeitet nach dem Fire-and-forget-Prinzip: Es gibt keine Fehlerereignisse und keine Empfangsbestätigung. Ein Steuerereignis, das nicht ausgeführt wird, bleibt ohne Abschlussereignis; die Ursache steht im Modul-Log:

Situation	Verhalten
Keine gültige Modullizenz	Steuerereignis wird verworfen (Log-Eintrag).
ExecuteDeleteCallData ohne confirmed = true	Verworfen — die Löschung ist unwiderruflich und verlangt die ausdrückliche Bestätigung.
ExecuteProvisionDevices ohne type	Verworfen.
ExecuteUserTemplate mit unbekannter templateId oder leerer Kontenliste	Verworfen.
ExecuteStarfaceRestart mit ungültigem mode	Verworfen (Log-Eintrag).
ExecuteStarfaceUpdate mit nicht verfügbarer Zielversion oder ohne verfügbares Update	Verworfen (Log-Eintrag).
ExecuteModuleInstallation, das abgelehnt wird	Ausnahme vom Fire-and-forget-Prinzip: Das ausführende Modul sendet ModuleInstallationExecutedEvent mit success = false und Fehlercode.
ExecuteModuleInstallation an ein Modul, das nicht installiert oder inaktiv ist	Keine Antwort.
AttentionEvent ohne subject	Verworfen (Log-Eintrag).
AttentionEvent mit unbekannter severity (auch kleingeschrieben, z. B. error)	Wird als WARNING behandelt – im Systemreport und im StarfleetController.
Unbekannte Felder in der Nutzlast	Werden ignoriert; das Ereignis wird normal verarbeitet.
Unbekannter Wert in trigger	Wird wie EVENT behandelt.

Ausbleibende Abschlussereignisse sind damit das Signal, im Modul-Log nachzusehen — außer bei den Systemaktionen Neustart und Update, die grundsätzlich keines senden.

Versionierung & Kompatibilität

Ereignisnamen und Feldnamen sind stabile Verträge; Erweiterungen erfolgen additiv (neue Ereignisse, neue optionale Felder). Verarbeiten Sie Nutzlasten daher tolerant gegenüber zusätzlichen Feldern. Den anlagenweiten Ereigniskatalog mit Beispiel-Nutzlasten führt die Ereignisliste der EventBridge-Dokumentation; Änderungen an den Ereignissen dokumentieren die Release Notes der jeweiligen Modulversion.